OpenEdge Application Server:<br />Developing AppServer Applications Connect and disconnect procedures

Connect and Disconnect procedures encapsulate logic that executes whenever a client application establishes and terminates a connection with an AppServer. Functionality that might go in a Connect or Disconnect procedure includes authenticating client users, connecting or disconnecting client-specific databases, loading or storing the contents of client-specific temp-tables, or any other common actions required when each individual client connection begins or terminates.

Connect procedure

A Connect procedure executes in whatever AppServer agent handles the client connection request, before the connection request is accepted. If the Connect procedure completes with no error, the connection request from the client application is accepted. If the Connect procedure completes with an error return value (RETURN ERROR statement), the connection request is rejected.

You can specify the name of an AppServer Connect procedure using the Progress Explorer GUI or by setting the srvrConnectProc property in the AppServer properties file (ubroker.properties). If you specify this procedure, it runs as part of the connection process initiated when a Progress 4GL client application executes the CONNECT( ) method on a server handle or when an Open Client executes a corresponding connection method.

You can use this procedure to authenticate a client application’s request for a connection, or to perform any other initialization steps that you want executed each time a client application initiates an explicit connection request. For example, you might use it to store connection context using an application-specific context database or using the SERVER-CONNECTION-CONTEXT attribute on the SESSION handle (see the "Managing stateless and state-free connection context" section). Using the SERVER-CONNECTION-ID attribute, you can uniquely identify the connection. You can then gather the context identified with the connection and store it in the context database or marshall it into the SERVER-CONNECTION-CONTEXT attribute. Any AppServer procedure that executes on behalf of the connection can restore and resave this context as appropriate. For more information, see the "Activate and deactivate procedures" section.

If you specify a Connect procedure, you must define it with three character input parameters. The following is an example of how you can define these input parameters:


DEFINE INPUT PARAMETER user-id AS CHARACTER NO-UNDO. DEFINE INPUT PARAMETER password AS CHARACTER NO-UNDO. DEFINE INPUT PARAMETER app-server-info AS CHARACTER NO-UNDO.

When the AppServer Connect procedure runs, the values of these three parameters are the same as the corresponding parameters specified via the CONNECT( ) method. If a value is not specified for a parameter to the CONNECT( ) method, the AppServer Connect procedure receives the Unknown value (?) for that parameter.

OpenEdge does not examine the values passed from the CONNECT( ) method to an AppServer Connect procedure. The name of each character input parameter might suggest the content you define for it. For example, the user-id can contain user name information, the password can contain password information, and the app-server-info can contain other user-defined information needed by the AppServer Connect procedure to complete a connection. However, the requirement to specify a particular value for the CONNECT( ) method is based only on the implementation of your AppServer Connect procedure. After examining the values provided to the AppServer Connect procedure, you can reject the connection request from the client application by terminating the procedure with the RETURN ERROR statement.

Disconnect procedure

A Disconnect procedure executes in whatever AppServer agent handles a client disconnection request, but before the connection is terminated. You can use the AppServer Disconnect procedure to specify logic that you want executed at this time. For example, you might want to use it to disconnect from a client-specific database or from other AppServers that were connected on behalf of the client.

You can specify the name of an AppServer Disconnect procedure using the Progress Explorer GUI or by setting the srvrDisconnProc property in the AppServer properties file (ubroker.properties). This procedure takes no parameters.

For an AppServer running in state-reset or state-aware operating mode, the Disconnect procedure runs after the AppServer returns the response to the client disconnection request to the client application. For a stateless AppServer, the procedure runs just before the AppServer returns this disconnection response, where it is typically used to delete connection-specific context. Any raised conditions that you do not handle in this procedure are ignored by OpenEdge.

Usage requirements

You can specify Connect and Disconnect procedures for all three AppServer operating modes (state-reset, state-aware, and stateless).

If the AppServer operating mode is state-reset or state-aware, the Connect procedure runs as a persistent procedure. If the AppServer operating mode is stateless, the Connect procedure runs as a non-persistent procedure. The Disconnect procedure runs as a non-persistent procedure in all operating modes.

If the Connect procedure is executed as a persistent procedure, and you do not need its context, you can delete it by executing the DELETE PROCEDURE (or DELETE OBJECT) statement on the procedure handle associated with the Connect procedure. If the AppServer operating mode is state-reset, the persistent Connect procedure is automatically deleted when a new connection is assigned to the AppServer agent.

Note that if the AppServer is running in stateless operating mode, there is no guarantee that the AppServer agent that runs the Connect procedure for the client application will be the same one that actually processes requests for the client application. Thus, any context that a Connect procedure establishes for a stateless connection must be stored in a file, database, SERVER-CONNECTION-CONTEXT attribute of the SESSION handle (see the "Managing stateless and state-free connection context" section), or some other resource that is accessible through the Progress 4GL.

Note that both the Connect and Disconnect procedures are optional. There is no requirement to specify either or both of them. Additionally, the content of these procedures is completely application specific, and the AppServer architecture places no constraints on it. Any Progress 4GL logic that is valid within an AppServer agent is valid for these procedures.